Skip Headers

Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# OCI Table Functions

This section describes the OCI Table functions.

Table 18-18 Table Functions

Function/Page | Purpose
--- | ---
OCITableDelete() | Delete element
OCITableExists() | Test whether element exists
OCITableFirst() | Return first index of table
OCITableLast() | Return last index of table
OCITableNext() | Return next available index of table
OCITablePrev() | Return previous available index of table
OCITableSize() | Return current size of table

## OCITableDelete()

Purpose

Deletes the element at the specified index.

Syntax

    sword OCITableDelete ( OCIEnv          *env,
                           OCIError        *err,
                           sb4             index,
                           OCITable        *tbl );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

index (IN)

  Index of the element which must be deleted.

tbl (IN)

  Table whose element is deleted.

Comments

This function returns an error if the element at the given index has already been deleted or if the given index is not valid for the given table. It is also an error if any input parameter is `NULL`.

Note: The position ordinals of the remaining elements of the table are not changed by `OCITableDelete()`. The delete operation creates holes in the table.

Related Functions

OCIErrorGet(), OCITableExists()

## OCITableExists()

Purpose

Tests whether an element exists at the given index.

Syntax

    sword OCITableExists ( OCIEnv              *env,
                           OCIError            *err,
                           CONST OCITable      *tbl,
                           sb4                 index,
                           boolean             *exists );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

tbl (IN)

  Table in which the given index is checked.

index (IN)

  Index of the element which is checked for existence.

exists (OUT)

  Set to `TRUE` if element at given `index` exists; otherwise, it is set to `FALSE`.

Comments

This function returns an error if any input parameter is `NULL`.

Related Functions

OCIErrorGet(), OCITableDelete()

## OCITableFirst()

Purpose

Returns the index of the first existing element in a given table.

Syntax

    sword OCITableFirst ( OCIEnv             *env,
                          OCIError           *err,
                          CONST OCITable     *tbl,
                          sb4                *index  );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

tbl (IN)

  Table to scan.

index (OUT)

  First index of the element which exists in the given table is returned.

Comments

For example, if `OCITableDelete()` deleted the first 5 elements of a table, `OCITableFirst()` returns 6.

See Also: OCITableDelete() for information regarding non-data holes in tables.

This function returns an error if the table is empty.

Related Functions

OCIErrorGet(), OCITableDelete(), OCITableLast()

## OCITableLast()

Purpose

Returns the index of the last existing element of a table.

Syntax

    sword OCITableLast ( OCIEnv              *env,
                         OCIError            *err,
                         CONST OCITable      *tbl,
                         sb4                 *index );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

tbl (IN)

  Table to scan.

index (OUT)

  Index of the last existing element in the table.

Comments

This function returns an error if the table is empty.

Related Functions

OCIErrorGet(), OCITableFirst(), OCITableNext(), OCITablePrev()

## OCITableNext()

Purpose

Returns the index of the next existing element of a table.

Syntax

    sword OCITableNext ( OCIEnv             *env,
                         OCIError           *err,
                         sb4                index,
                         CONST OCITable     *tbl,
                         sb4                *next_index
                         boolean            *exists );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

index (IN)

  Index for starting point of scan.

tbl (IN)

  Table to scan.

next_index (OUT)

  Index of the next existing element after `tbl`(`index`).

exists (OUT)

  `FALSE` if no next index is available, else `TRUE`.

Comments

Returns the smallest position j, greater than `index`, such that `exists(j)` is `TRUE`.

See Also: Refer to the description of OCIStringAllocSize(), regarding the existence of non-data holes in tables.

Related Functions

OCIErrorGet(), OCITablePrev()

## OCITablePrev()

Purpose

Returns the index of the previous existing element of a table.

Syntax

    sword OCITablePrev ( OCIEnv             *env,
                         OCIError           *err,
                         sb4                index,
                         CONST OCITable     *tbl,
                         sb4                *prev_index
                         boolean            *exists );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

index (IN)

  Index for starting point of scan.

tbl (IN)

  Table to scan.

prev_index (OUT)

  Index of the previous existing element before `tbl`(`index`).

exists (OUT)

  `FALSE` if no previous index is available, else `TRUE`.

Comments

Return the largest position `j`, less than `index`, such that exists(`j`) is `TRUE`.

See Also: Refer to the description of OCIStringAllocSize(), regarding the existence of non-data holes in tables.

Related Functions

OCITableNext()

## OCITableSize()

Purpose

Returns the size of the given table, not including deleted elements.

Syntax

    sword OCITableSize ( OCIEnv             *env,
                         OCIError           *err,
                         CONST OCITable     *tbl
                         sb4                *size );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode.

  See Also: OCIEnvCreate() and OCIInitialize()

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

tbl (IN)

  Nested table whose number of elements is returned.

size (OUT)

  Current number of elements in the nested table. The count does not include deleted elements.

Comments

The count will be decremented upon deleting elements from the nested table. So this count does not include any holes created by deleting elements. To get the count not including the deleted elements, use OCICollSize().

For example:

    OCITableSize(...);
    // assume 'size' returned is equal to 5
    OCITableDelete(...); // delete one element
    OCITableSize(...);
    // 'size' returned is equal to 4

To get the count plus the count of deleted elements use `OCICollSize()`. Continuing the previous example:

    OCICollSize(...)
    // 'size' returned is still equal to 5

This function returns an error if an error occurs during the loading of the nested table into the object cache, or if any of the input parameters is `NULL`.

Related Functions

OCICollSize()